﻿//-----------------------------------------------------------------------------------------
// <copyright file="Accelerometer.cs" company="Jakub Florczyk (www.jakubflorczyk.pl)">
//      Copyright © 2009 Jakub Florczyk (www.jakubflorczyk.pl)
//      http://samsungmobilesdknet.codeplex.com
// </copyright>
//-----------------------------------------------------------------------------------------

namespace SamsungMobileSDKNET
{
    using System.Runtime.InteropServices;

    /// <summary>
    /// Function signature for accelerometer event handlers.
    /// </summary>
    /// <param name="accel">Accelerometer vector data.</param>
    public delegate void AccelerometerEventHandler(
        AccelerometerVector accel);

    /// <summary>
    /// Accelerometer vector data.
    /// </summary>
    [StructLayout(LayoutKind.Sequential)]
    public struct AccelerometerVector
    {
        /// <summary>
        /// X-direction value.
        /// </summary>
        public float X;

        /// <summary>
        /// Y-direction value.
        /// </summary>
        public float Y;

        /// <summary>
        /// Z-direction value.
        /// </summary>
        public float Z;
    }

    /// <summary>
    /// Specifies the capabilities of the Accelerometer device.
    /// </summary>
    [StructLayout(LayoutKind.Sequential)]
    public struct AccelerometerCapabilities
    {
        /// <summary>
        /// The unit of the vector sampling time, in milliseconds.
        /// </summary>
        public uint CallbackPeriod;
    }

    /// <summary>
    /// Samsung accelerometer API.
    /// </summary>
    /// <remarks>
    /// The Samsung accelerometer API enables applications to synchronously or asynchronously obtain acceleration values in the X, Y, and Z axis directions. Accelerometers can measure acceleration in one, two, or three directions, depending on their capabilities. (Samsung devices typically support 3-axis accelerometers.)
    /// <br/><br/>
    /// Accelerometers measure the acceleration in terms of Earth’s gravitational force, or 'g' (9.8m/sec˛). 
    /// <br/>
    /// The sensitivity, or resolution, of the acceleration values along each axis and the directions of the accelerometer axes vary from device to device. These are not specified by the Samsung accelerometer API.
    /// <br/>
    /// Please refer to device-specific documentation for these details.
    /// </remarks>
    public class Accelerometer
    {
        /// <summary>
        /// Gets the capabilities of the accelerometer device.
        /// </summary>
        /// <param name="capabilities">A pointer to the capabilities of the device.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiAccelerometerGetCapabilities")]
        public static extern ResultCode GetCapabilities(
            [Out] out AccelerometerCapabilities capabilities);

        /// <summary>
        /// Gets the device's current acceleration along the X, Y, and Z axes, in terms of g.
        /// </summary>
        /// <param name="accel">Acceleration of the device.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiAccelerometerGetVector")]
        public static extern ResultCode GetVector(
            [Out] out AccelerometerVector accel);

        /// <summary>
        /// Start receiving accelerometer data periodically.
        /// <br/><br/>
        /// The period interval must be a multiple of the callbackPeriod specified in SmiAccelerometerCapabilities. If it is less than the callbackPeriod, it will be set to the callbackPeriod. If it is not a multiple of the callbackPeriod, it will be truncated to fit the value. ( (period / callbackPeriod) * callbackPeriod )
        /// <br/><br/>
        /// Only one handler per process is allowed. Successive calls per process will replace the previous handler function and period.
        /// </summary>
        /// <param name="period">Callback interval.</param>
        /// <param name="handler">Callback function for every period interval.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the handler input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiAccelerometerRegisterHandler")]
        public static extern ResultCode RegisterHandler(
            [In] uint period,
            [In] AccelerometerEventHandler handler);

        /// <summary>
        /// Stop receiving accelerometer data periodically.
        /// </summary>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiAccelerometerUnregisterHandler")]
        public static extern ResultCode UnregisterHandler();        
    }
}
